Subject: Directory proposal

From: "Hildebrand, Jeff" <[email-masked]>
Date: Thu, 01 Jul 93 16:20:00 PDT

To CIW members
From Jeff Hildebrand - Boeing Computer services
     [email-masked]

Subject: CPI-C naming and addressing

This paper describes several issues concerning the current proposal for
directory services, and proposes a solution which resolves them.

Problems:

The directory service proposal and the discussion surrounding it
have focused on what directory to use, (X.500, DCE Cell, none), not
how CPI-C should use directory services.  This is an important
difference because it profoundly affects the way the API
is procured by end users and manufactured by vendors.

If a specific directory mechanism is chosen it means that the
the user must procure it if he is to effectively use the API and
all vendors must build to it - they have no option.  This obviously
is not a tenable position - after all no two users or vendors are
the same.  This view is typically expressed to me when a vendor says
"Yeah, but I support a lot of small shops that aren't like Boeing".
What we are really interested in is how to use a directory - not which
directory mechanism is used - the directory is a transparent service.

A transparent directory service, that is acceptable to all, does not
exist, which is why the current directory service proposal
is so controversial.  CPI-C, then, must be able to use any
directory service mechanism a user or vendor wants to use or sell.
These directory service mechanisms include X.500, DCE Cell directories,
VSAM flat files, DB2 databases, etc. How this can be accomplished is for
CPI-C to provide a generic interface to directory services and specify
what it expects back from the directory.  In concrete terms this means:
     1. Passing a name, typically known as a sym-dest-name, to the
        directory service mechanism.
     2. The CPI-C implementation gets back the necessary data
        to configure the necessary internal control blocks.

This proposal specifies a way that names can be passed to the directory
service mechanism in a manner that is traditional to CPI-C and yet allows
for any name form to be used (see service text at the end of this paper).
It is an extension of the CMINIT service, called
CMINITA (CMINIT with Expanded Addressing).  CMINIT is not obsoleted, as it
maps to the CMINITA service.  What the CMINITA service does is add two
parameters to the CMINIT that specify the length of the sym-dest-name and
what name space it is drawn from.  This approach has several advantages:

     1. It scales for every user and vendor implementation.  For
        small installations flat files can be supported, for large
        installations X.500.  The vendor is only required to make
        interfaces for the directory mechanisms they choose to
        support.  The vendors do not have to produce any directory
        service mechanism themselves.  This also leaves a lot of room
        for vendors to provide value-added services.

     2. It allows the external administration of CPI-C programs, so
        that the CPIC-C application program can adapt
        to changes in its environment without either recompiling it
        or disturbing the programmer.  This works out really
        well for 'shrink wrapped' programs which require the
        sym-dest-name  be generated by the developer but administered
        by the user.  A couple of areas in which vendors could provide
        significant value-added services are:

          A. Directory service administration tools.
          B. Directory user agents which support
             complex yellow pages schemes.

I would like to preempt two potential issues:
     1. Yellow pages.
     2. Name space support problems.

Yellow pages:  The application programmer does not decide how a program
searches for partners, his only concern is that it finds the correct
partner.  This implies that the use of yellow pages is an administrative
decision.  Administrative decisions are best taken care of in the directory
or by the directory user agent.  These two roles are well defined for X.500.
For VSAM files these roles can easily be defined by the vendor.  One day
the administrator decides that a program should use yellow pages look up so
that server loads can be balanced, so he makes the proper entries in the
directory and it's done.  This provides an extremely fertile area for
vendors to supply value-added solutions, for example how does one keep
track of server loadings and makes yellow pages selection decisions.

Putting the decision to use or not to use Yellow Pages inside the program
itself is a big mistake.  'Shrink wrapped' vendors should be very wary of
any requirement that they be forced to specify if their program use
yellow pages or not.  Do you specify yellow pages look up for
all your programs and let the user sort it out. Or, do you decide
which of your programs are suited to yellow pages and which are not - always
hoping your customers agree with you.

Name Space Support:  The proposal has the programmer specifying what
name space the sym-dest-name is drawn from so that the directory mechanism
can handle it correctly.  For example if a relative distinguished name
was specified an X.500 directory user agent might append it to a
default RDN to form a distinguished name.  It essentially allows the
underlying mechanism to intelligently handle the name.

If the underlying mechanism is very simple - like a flat file, the name
would simply be used as a string of characters.  This is possible because
the underlying mechanism is responsible for resolving the name.

There is one special name space that is specified - LOCAL.  This name
space is a catch all and means that there is no recognized naming
scheme that was responsible for creating this name.  The
current 8 character sym-dest-name is an example of this, some local set
of people decided on a site specific naming scheme and use it
with CPI-C.

Where to go from here:

I would like to resolve the directory problem this summer.  I would
encourage all of those interested in the topic to start
an EMAIL debate on the subject.

Kindest regards,
Jeff  Hildebrand

 --------------------  TEXT for CMINITA Service 
 -------------------------------

Initialize_Conversation_Expanded_Address (CMINITA)

A program uses the Initialize_Conversation_Expanded_Address (CMINITA)
service to initialize values for various conversation characteristics
before the conversation is allocated (with a call to allocate).
This call supersedes the CMINIT call and allows the user to specify
both a symbolic_destination_name (sym_dest_name) longer than 8
characters and the name space the name comes ISO, SNA, or local.
The remote partner program uses the Accept_Conversation call to
initialize values for the conversation characteristics on its end
of the conversation.

Note: A program can override some values that are initialized by
this call using the appropriate Set calls, such as SET_Sync_level.
Once the value is changed, it remains changed until the end of the
conversation or until changed again by a Set call.

Format

CALL CMINITA   (conversation_ID,
               sym_dest_name_space,
               sym_dest_name_length
               sym_dest_name
               return_code)

Parameters
     Conversation_ID (output)
          Specifies the variable containing the conversation identifier
          assigned to the conversation.  CPI-Communications
          supplies and maintains the conversation_ID.  If the
          Initialize_Conversation_Expanded_Address call is
          successful (return_code is set to CM_OK), the local
          program uses the identifier returned in this variable for
          the rest of the conversation.

     Sym_Dest_Name_Space (input)
          Specifies the name space the sym_dest_name is drawn
          from.  This allows correct processing of the
          sym_dest_name by the side information storage
          mechanism.  Valid values for this variable are:
*         CM_NONE
          No sym_dest_name is supplied, equivalent to a blank
          sym_dest_name.
*         CM_ISO_DN
          Indicates a distinguished name.
*         CM_ISO_RDN
          Indicates a relative distinguished name.
*         CM_ISO_OID
          Indicates an object identifier.
*         CM_SNA
          Indicates a partner_LU_name.
*         CM_LOCAL
          Indicates local naming conventions.

     Sym_dest_name_length (input)
          Specifies the symbolic destination name.  The symbolic
          destination name is provided by the program and points to
          a side information entry.  The appropriate entry is
          retrieved and used to initialize the characteristics for
          the conversation.  Alternatively, sym_dest_name_space
          could be set to CM_NONE.  When this is done, the program
          is responsible for setting up the appropriate destination
          information, using Set calls, before issuing the Allocate
          call for that conversation.  How side information is
          stored is a local matter.

     Sym_dest_name (input)
          Specifies the variable containing the conversation identifier
          assigned to the conversation.  CPI-Communications
          supplies and maintains the conversation_ID.  If the
          Initialize_Conversation_Expanded_Address call is
          successful (return_code is set to CM_OK), the local
          program uses the identifier returned in this variable
          for the rest of the conversation.

     return_code (output)
          Specifies the result of call execution.  The return_code
          variable can have one of the following values:
*        CM_OK
*        CM_PROGRAM_STATE_CHECK
          This value indicates that the sym_dest_name specifies
          an unrecognized value.
*        CM_OPERATION_NOT_ACCEPTED
          This value indicates the sym_dest_name_space value
          was not valid for the local side information mechanism.
*        CM_PRODUCT_SPECIFIC_ERROR

State Changes
When the return_code indicates CM_OK, the conversation enters the
INITIAL state.

Usage Notes
1. For a list of the conversation characteristics that are
   initialized when the Initialize_conversation_expanded_address
   call completes successfully, see Table 3 on page 20.

2. For each conversation, CPI-Communications assigns a
   unique identifier, the conversation_ID.  The program
   then uses the Conversation_ID in all future calls
   intended for that conversation.
   Initialize_conversation_expanded_address (or
   Accept_Conversation or Initialize_For_incoming, on the
   opposite side of the conversation) must be issued by
   the program before any other calls may be made for
   that conversation.

3. Program can call
   Initialize_conversation_expanded_address more than
   once and establish multiple, concurrently active
   conversations.  When a program with an existing
   initialized conversation issues an
   Initialize_conversation_expanded_address call,
   CPI-Communications initializes a new conversation and
   assigns a new conversation_ID.  CPI-Communications
   is designed so that
   Initialize_conversation_expanded_address is always
   issued from the Reset state.  For more information
   about managing concurrent conversations, see
  "Multiple Conversations" on page 15.

4. If the side information is invalid, or the program supplies
   invalid allocation information via Set calls, the error is
   detected when the information is processed by Allocate
   (CMALLC).

5. A program may obtain information about its partner
   program in the following manner:

     A. Side information: This method uses a
        sym_dest_name to access an entry from the side
        information mechanism.  Side information may be
        held in any manner the local system deems fit, i.e.,
        flat files, X.500 directories, or other directory
        mechanisms.  OSI addressing information can only
        be retrieved from side information, there are no set
        calls to set this information from within the program.

     B. Hard-coded: This method uses Set Calls to hard-code
        SNA addressing information from within the program.
             In this case, the local program sets
        sym_dest_name_space to CM_LOCAL on the
        Initialize_conversation_expanded_address call.
        CPI-Communications will initialize the conversation
        characteristics and return a conversation_ID for the
        new conversation.  The program is then responsible
        for specifying valid destination information (using
        Set_partner_LU_Name, Set_TP_Name, and
        Set_Mode_Name calls) before issuing the Allocate
        call.

Related Information

When the Initialize_Conversation (CMINIT) call is issued by an application
program, CPI-C maps the call to the Initialize_conversation_expanded_address 

call by automatically:
     1.Setting the sym_dest_name_space to CM_LOCAL.
     2.Setting the sym_dest_name_length to 8.
     3.Setting the sym_dest_name on the
       Initialize_conversation_expanded_address call to the
       sym_dest_name on the Initialize_Conversation call.
     or
     4. If the sym_dest_name on the Initialize_conversation call
        is set to blanks, the sym_dest_name_space is set
        to CM_NONE.

"Conversation Characteristics" on page 18  provides a general overview
of conversation  characteristics and how they are used by the program
and CPI-Communications. "Example 1: Data Flow in One Direction" on page 37
shows an example program flow where Initialize_Conversation_Expanded_Address
is used. The calls beginning with "Set" and "Extract" in this chapter are
used to modify or examine certain conversation characteristics established
by the Initialize_conversation_expanded_address program call; see the
individual call descriptions for details.
"Side Information"  on page 11 provides more information on sym_dest_name.

 This table must be modified to include the following OSI entities, 
AE-title,
 AP-title, TPSU-title, and NSAP.  This work is currently being done in the
 CPI-C Implementors Workshop (CIW). The description on page 11 must be
updated to reflect OSI TP requirements.